package simpledb.storage;

import simpledb.common.DbException;
import simpledb.transaction.TransactionAbortedException;

import java.util.NoSuchElementException;

/**
 * DbFileIterator 是一个数据库文件迭代器接口，用于遍历某个 DbFile（即一张表）中的所有元组（tuple）。
 * 它是 SimpleDB 存储层中数据访问的核心抽象之一。
 * 该接口定义了常见的迭代器操作方法：
 * 1、打开迭代器
 * 2、检查是否有下一个元组
 * 3、获取下一个元组
 * 4、重置迭代器
 * 5、关闭迭代器
 * 这些方法使得上层模块（如查询执行引擎）可以以统一的方式遍历存储在磁盘或缓冲池中的数据。
 * DbFileIterator 是所有 SimpleDB 数据库文件应实现的迭代器接口。
 * 它用于逐条读取 DbFile 中的元组（Tuple），支持打开、关闭、重置等操作。
 */
public interface DbFileIterator {

    /**
     * 打开迭代器，准备开始遍历元组。
     * 通常在此阶段初始化底层资源（如获取页面、建立扫描器等）。
     *
     * @throws DbException 如果在打开过程中发生数据库错误
     * @throws TransactionAbortedException 如果事务被中断
     */
    void open() throws DbException, TransactionAbortedException;

    /**
     * 判断是否还有下一个元组可供读取。
     * 可能返回 false 的情况包括：
     * - 已经遍历完所有元组
     * - 迭代器未打开
     *
     * @return 如果有下一个元组则返回 true，否则返回 false
     * @throws DbException 如果在检查时发生数据库错误
     * @throws TransactionAbortedException 如果事务被中断
     */
    boolean hasNext() throws DbException, TransactionAbortedException;

    /**
     * 获取下一个元组。
     *
     * @return 下一个 Tuple 对象
     * @throws NoSuchElementException 如果没有更多元组可读
     * @throws DbException 如果在读取过程中发生数据库错误
     * @throws TransactionAbortedException 如果事务被中断
     */
    Tuple next() throws DbException, TransactionAbortedException, NoSuchElementException;

    /**
     * 将迭代器重置到起始位置，以便重新开始遍历。
     * 某些实现可能不支持此操作，此时抛出 DbException。
     *
     * @throws DbException 当不支持 rewind 操作时抛出
     * @throws TransactionAbortedException 如果事务被中断
     */
    void rewind() throws DbException, TransactionAbortedException;

    /**
     * 关闭迭代器，释放相关资源（如锁、缓冲池页面等）。
     */
    void close();
}
